-
Notifications
You must be signed in to change notification settings - Fork 49
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Prettier support #31
Prettier support #31
Conversation
Based on proposal in #31 > Prettier likes to format embedded code blocks in our markdown. Generally, we like this too, except when we don't. Sometimes we deliberately want to format something "weird" to demonstrate that our language supports that; in those cases we don't want prettier to undo our "weird" formatting. To achieve this, we can use a raw codeblock However the implementation differs by requiring a space before the language name (which still thwarts tools like GH and prettier) and makes this part of the parsed AST rather than part of the highlight function name.
Based on proposal in #31 > Prettier likes to format embedded code blocks in our markdown. Generally, we like this too, except when we don't. Sometimes we deliberately want to format something "weird" to demonstrate that our language supports that; in those cases we don't want prettier to undo our "weird" formatting. To achieve this, we can use a raw codeblock However the implementation differs by requiring a space before the language name (which still thwarts tools like GH and prettier) and makes this part of the parsed AST rather than part of the highlight function name.
Based on #31, adds support for productions and algorithms to wrap around multiple lines.
Based on #31, adds support for productions and algorithms to wrap around multiple lines.
Based on #31, adds support for productions and algorithms to wrap around multiple lines.
Based on #31, adds support for productions and algorithms to wrap around multiple lines.
Based on #31, adds support for productions and algorithms to wrap around multiple lines.
Based on #31, adds support for productions and algorithms to wrap around multiple lines.
Based on #31, adds support for productions and algorithms to wrap around multiple lines.
Based on #31, adds support for productions and algorithms to wrap around multiple lines.
Based on #31, adds support for productions and algorithms to wrap around multiple lines.
Since GFM supports underscores for emphasis, we can do that here as well. Factored out of #31. Note that this is breaking since previously if you have ambiguous underscores in open text that it may create a syntax error or italicize text. To correct this replace `_` with `\_`.
Since GFM supports underscores for emphasis, we can do that here as well. Factored out of #31. Note that this is breaking since previously if you have ambiguous underscores in open text that it may create a syntax error or italicize text. To correct this replace `_` with `\_`.
Supports use of standard markdown headers (`# Header`) as the title of a spec markdown document. Inspired by a similar change in #31 however this does not require wrapping the header in bold. For some context, originally setext headers were required to differentiate between a document title and a section header in an imported file since spec-md did not differentiate between initial files and imported files. This change is possible by having pegjs support multiple starting positions for the parser and parse initial and imported documents differently. This also allows us to remove the ast validation logic since that can now be encoded directly in the grammar.
Supports use of standard markdown headers (`# Header`) as the title of a spec markdown document. Inspired by a similar change in #31 however this does not require wrapping the header in bold. For some context, originally setext headers were required to differentiate between a document title and a section header in an imported file since spec-md did not differentiate between initial files and imported files. This change is possible by having pegjs support multiple starting positions for the parser and parse initial and imported documents differently. This also allows us to remove the ast validation logic since that can now be encoded directly in the grammar.
Supports use of standard markdown headers (`# Header`) as the title of a spec markdown document. Inspired by a similar change in #31 however this does not require wrapping the header in bold. For some context, originally setext headers were required to differentiate between a document title and a section header in an imported file since spec-md did not differentiate between initial files and imported files. This change is possible by having pegjs support multiple starting positions for the parser and parse initial and imported documents differently. This also allows us to remove the ast validation logic since that can now be encoded directly in the grammar.
Inspired by #31, this moves markdown unencoding from the print step to the parse step, and in doing so applies it nearly everywhere that raw text is parsed, and no longer only `Text` nodes. This means escape sequences can be found within names, grammar terminals, prose, string literals, and section headers.
Inspired by #31, this moves markdown unencoding from the print step to the parse step, and in doing so applies it nearly everywhere that raw text is parsed, and no longer only `Text` nodes. This means escape sequences can be found within names, grammar terminals, prose, string literals, and section headers.
Inspired by #31, this moves markdown unencoding from the print step to the parse step, and in doing so applies it nearly everywhere that raw text is parsed, and no longer only `Text` nodes. This means escape sequences can be found within names, grammar terminals, prose, string literals, and section headers.
Incredible forward work - I took the liberty of breaking this draft PR into individual PRs for each proposed feature, mostly as you've implemented them here. At this point I've landed changes for every bullet you've detailed, so I'll close this draft |
Excellent! It'll be such a relief to have a tool automatically format the text for me (and for other contributors!) 😆 Whilst I don't agree with using bullets (which are semantically incorrect) over markdown linefeeds (which are pernickety), all your other changes definitely improve on my hacked out solutions. In particular the title (a bold h1 was definitely a hack!), and the |
This pull request adds support for spec-md parsing markdown that has been formatted by
prettier
. It has been tested against the GraphQL Spec only. It contains breaking changes.Most notable changes:
# **Title**
is another accepted format for the main document title (rather than relying on a single Setext-style header.)\*
,\_
and\$
are supported in many locations to support prettier's auto-escaping of ambigous markdown_
is now supported for emphasisraw
prefix on languagesTODO:
raw prefix on languages
Prettier likes to format embedded code blocks in our markdown. Generally, we like this too, except when we don't. Sometimes we deliberately want to format something "weird" to demonstrate that our language supports that; in those cases we don't want prettier to undo our "weird" formatting. To achieve this, we can use a raw codeblock:
We'll just trim the "raw" (unless it's legitimately the start of a language name that's supported by prismjs) and use the remaining text as the language to use for highlighting. This is much nicer (and more reliable) than putting
<!-- prettier-ignore -->
comments throughout the source markdown text.